home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / latex209 / contrib / genindex / readme < prev   
Text File  |  1993-08-08  |  5KB  |  88 lines
  1. If you examine the code in latex.tex (LATEX VERSION 2.09 <25 March 1992>)
  2. that defines the index- and glossary-making macros, you will see that
  3. \makeindex and \makeglossary are nearly identical, and that the definitions
  4. of \index and \glossary are nearly identical, "mutatis mutandis".
  5. That is, the index-making macros write an .idx file, and the
  6. glossary-making macros write a .glo file, but they do it in almost
  7. exactly the same way.  Reading the comments in the file leads one
  8. to believe that the \index feature was defined earlier, and the \glossary
  9. feature was added later as an adaptation of \index.
  10.  
  11. I recently needed to create a third kind of file that I wanted to
  12. be handled similarly to the .idx and .glo files, so I abstracted
  13. the definitions of the index and glossary macros into a separate
  14. style file.  Since I think of these as "generalized" index macros,
  15. I call it "genindex.sty".  I'm rather surprised that this wasn't
  16. done at the time the \glossary feature was added, since it seems like
  17. a natural extension.  It takes fewer lines of code to define a
  18. generalized structure and invoke it twice than it does to give
  19. separate definitions of \index and \glossary!
  20.  
  21. As indicated in the comments in genindex.sty, the index and glossary
  22. macros of latex.tex could be specified as follows:
  23.  
  24.        \newindex{index}{\@indexfile}{idx}{\indexentry}
  25.        \newindex{glossary}{\@glossaryfile}{glo}{\glossaryentry}
  26.  
  27. Actually, there is one discrepancy: the definition of \glossary
  28. in latex.tex does not include the definition of \protect, which
  29. means that a \glossary entry in a moving argument (such as a footnote)
  30. can get you into trouble.  Again, examining the comments in latex.tex
  31. suggests that \index was defined first, then \glossary was cloned from
  32. \index, and at a later date the \protect definition was added to \index
  33. as a bug fix but the fixer did not make the corresponding change
  34. to \glossary.  In any case, all index-like structures defined by \newindex
  35. define \protect the way the standard \index macro does, so they are safe
  36. to use wherever \index may be used.
  37.  
  38. (Incidentally, the eight # marks in a row in the body of \newindex are
  39. a record for me.  \newindex defines macros like \makeindex, which
  40. define macros like \index, which define the macro \protect.
  41. This is the deepest nesting of macros defining macros I've ever
  42. had occasion to use.)
  43.  
  44. The particular application that moved me to do this was the ability to
  45. make memos to myself in the source files for a book.  I'm working with
  46. a co-author, and we both want to be able to place little notes in
  47. the source that will remind us of issues to consider as we develop the
  48. book, but we don't want theses notes to be visible in the typeset pages.
  49. We used to use comments, but it's easy to overlook comments in the source
  50. files.  We each are especially prone to overlook the other's comments
  51. since we don't know where to expect them.  By using the \memo macro we
  52. get all the memos written to a separate file, with each memo keyed to
  53. the page to which it applies.  We can run the book and then read the .mem
  54. file to see the reminders we've made.  Note that unlike the .idx and .glo
  55. files, the .mem file is not processed by makeindex or other utility and
  56. read back into LaTeX (although I've considered making a *separate* driver
  57. file that would read another document's .mem file and make a nice list
  58. of the memos).  With the generalized index macros above it is easy to
  59. define the \memo macro:
  60.  
  61. =============================================================================
  62.  
  63. Note that I go ahead and execute \makememo within memo.sty, since I
  64. always want the \memo command to be active.  Now I can place \memo{ENTRY}
  65. in the source and have \memoentry{ENTRY}{PAGENUM} in the .mem file with
  66. no effect on the typeset pages.  (Well, no more effect than \index
  67. would have.)
  68.  
  69. I offer this in hopes it will be useful to others.
  70. Comments and suggestions for improvement are welcome.
  71.  
  72. By the way, if the \index and \glossary functions are to retain
  73. anything like their present form in the new, improved LaTeX descendants
  74. that are going to appear Real Soon Now, then I strongly suggest that
  75. this generalized approach be used.  I think the fact that the original
  76. \index functionality has been adapted twice (\glossary and \memo)
  77. is evidence that a generalized capability would be useful.
  78. I'm sure that other LaTeX users will think (or have already thought) of
  79. additional uses for this idea.
  80.  
  81. --Cameron Smith
  82.   cameron@symcom.math.uiuc.edu
  83.  
  84. P.S. Archivists, please feel free to put the above in an archive in
  85.     whatever form you deem suitable.
  86.  
  87.  
  88.